           Documentation for SUPER ARC version 2.0 and SUPER UN-ARC version 2.3                            By: Robert Puff  11/21/88                                       WHAT IS ARC?                 Arc is short for Archive. It is a program (actually in this     case, two programs) that allow you to "Archive" or compress one or     more files into a single .ARC file for later retrieval.  Arc is     available for many computer types; a file created on one will be able     to be unarced on another.  The only exception to this that I am aware     of is the CP/M version of Arc for the Commodore.  Super Arc uses     several mathematical compression techniques to reduce the size of the     data to be compacted by as much as possible.  "Why would you do that"     you ask?  A number of reasons, but primarily Time - Time is money.     This can be realized when downloading a file from a long-distance     BBS, or from a pay service such as CompuServe or GEnie.  Super Arc     will compact your file(s) as much as it possibly can, which averages     around 30%.  As a bonus, Super Un-Arc will uncrunch files created     with AlfCrunch, so separate programs are not required!  Also included     in Super Un-Arc is the code necessary to un-squash files.  Squashed     files are created by Phil Katz's PKPAK utility for the PC.  This     makes Super Un-Arc THE most compatible unarchiver for the 8-bit!  You     must, however have an expanded machine for this feature.                 Arc is not the same thing as Diskcomm (Disk Communicator, a     program I wrote back in '87.).  Diskcomm is designed to compact     entire floppy disks sector-by-sector, making an exact copy of the     disk; while Arc is file-oriented.  What this all means is if you have     a disk that is self booting, or looks for data in specific sectors,     you should use Diskcomm to turn that disk into a file for easy     transfer.  If however, you wish to transfer only a few of the files     on the disk, or the files on the disk are not dependent on being     specifically located at a certain sector, then Arc is the program to     use.  Please remember that Disk Operating Systems (DOS) look for     specific sectors, so they should NOT be compacted by Arc.  Diskcomm,     while it does have compaction techniques, is not as sophisticated as     Arc; so if you REALLY want to make the smallest file of a boot disk,     you could Arc the Diskcommed file.  Be sure, however, that the person     receiving your file knows he must go through two processes to recover     the disk: UnArcing the file, then unDiskcomming the resulting file!                                 SETTING UP SUPER ARC & SUPER UN-ARC                 Both of the files, ARC.COM and UNARC.COM are binary, command     files.  This means they should be loaded from your DOS menu by     selecting the LOAD BINARY FILE option.  If you are using a command     processor DOS (such as DOS XL or SpartaDOS), simply type the first     part of the filename at the prompt.  If you are using Atari DOS 2.5     with the RAMdisk handler, you will need to do a little more in     set-up.  Go to your DOS menu, and do the following:     1. [C]opy DOS25.MOD,ARC.OBJ     2. [C]opy DOS25.MOD,UNARC.OBJ     3. [C]opy ARC.COM,ARC.OBJ/A     4. [C]opy UNARC.COM,UNARC.OBJ/A     What you have just done is added a patch to the beginning of Arc &     Unarc, to fix a bug in DOS 2.5.  Use the ARC.OBJ and UNARC.OBJ files     now; both ARC.COM and UNARC.COM may be deleted.                 You may wish to set up Super Arc & UnArc on a separate disk     with a menu program.  There are many public domain menu programs that     will fit the bill; just be sure the loader program is capable of     loading Binary files, not (just) BASIC programs.  Super Arc & UnArc     will automatically disable the internal BASIC on XL/XE machines, so     there is no NEED to hold the OPTION key when booting.  (SpartaDOS is     the only exception to this rule: because of a bug, BASIC will not be     turned off.)  Technical note: Super Arc & UnArc initially load in at     $6F00, then relocate themselves to LOMEM.  Thus there is no conflict     with a certain value of lomem.  If the size between LOMEM and HIMEM     is insufficient, the program will print the message "NOT ENOUGH     MEMORY" and exit.                                           USING SUPER ARC                 Once the program has loaded, you will be presented with a     number of parameters on the top of the screen, and a menu.  (If you     are using a command processor DOS, you may specify commands on the     command line as an alternative of using the menu.  Please see the     section below entitled 'USING SUPER ARC WITH CP DOSES'.)  First, the     parameters will be discussed.  To modify them, press [P], then use     the arrow keys to move to the desired parameter. Now hit [RETURN] to     toggle between YES and NO.  Press [ESC] when finished.                 Screen Off:  If this option is enabled, the screen will narrow     to a single status line in the middle of your screen during the     compaction process.  This will increase processing time by 30%.  If     there is a need for more user-input, or if any errors occur, the     screen will be restored.  If this option is set to NO, the screen     will remain unchanged.                 Disk Swaps:  This option is for single-drive users.  If this     option is enabled, you may use a different disk as your destination     (using the same drive).  This is helpful when the source and     destination will not all fit on one disk.  Make sure that your source     and destination disks are formatted in the same density!  Also,     follow the prompts VERY carefully.  If this option is set to NO, or     if you specify different source and destination drives, you will not     be prompted.                 Compact with Query:  If this option is set to YES, as Super     Arc finds each file, you will be asked if you wish to compact it.     This is useful for selecting exactly which files on a disk you want     to include in the archive.  At the prompt, you may answer [Y]es to     compact the file, [N]o to skip it, [P] to change the source     drive/mask, [1-9] for disk directories, or [ESC] to finish arcing.     If this option is set to NO, all files found will be compacted.                 Crunch Only:  A brief explanation of the arcing process is in     order here.  When you compress a file with Super Arc when this option     is set to NO (it defaults to NO), the program first analyzes the data     in the first pass to determine which of the three types of     compression would create the smallest file.  The three types are:     Storing, where no compaction is done; Packing, where repeated bytes     are "packed", and Crunched, where the data is run through a     sophisticated compressing routine.  It then reads the source a second     time, actually compacting the data this time.  The "Crunching" method     of compaction is usually the method used most often (perhaps 90%).     If this option is set to YES, Super Unarc will not analyze the file;     it will only Crunch it.  This takes only 1/2 the time, since the     compaction process is done only once instead of twice.  The     disadvantage is that on those files that will not benefit from     Crunching, you will not have the smallest possible file.     High-resolution picture files usually fall into this category.          Special note for SpartaDOS users: If you set the Crunch Only option     to YES, Super Arc will initially crunch the data, but if it     determines that Crunching is not the best, it will re-write the file     using the best method.  This may seem to be the best of both worlds;     however, the file will still be the same length.  If you add more     files to the archive, the unused space will disappear.  What this all     means is that if you want the smallest file possible, leave this     option set to NO.  If you want to do it quick, and aren't too     concerned with size, set this to YES.                 Password Encrypt:  Setting this option to YES will cause the     arced file to be encrypted with a special password you enter.  The     only way to recover the file created will be if the person unarcing     your file enters the same password you used.  I STRONGLY recommend     you not use this feature often, because it is HIGHLY unlikely you     will be able to recover the file without it.  The password is not     hidden anywhere in the file, so you can't look for it.  When this     option is set to YES, Super Arc will ask for the password after you     have entered the destination filename.  Pressing [RETURN] will cancel     the password, and continue as normal.  The password is not case or     inverse sensitive, but should not contain any spaces if you wish to     use an IBM or ST to unarc the file.  Setting this Password Encrypt     option to NO (as it is by default) will not use any password data,     and will compact as normal.                 Those are the parameters that are on the top of the screen.     On the main menu, there are more options.  You may format a floppy or     RAMdisk in either single or double density by typing [F].  Selecting     [D] will allow you to delete file(s).  You may use these two options     to prepare your destination disk for the destination file.                 Selecting [G] will cause your computer to reboot (act as if it     had been turned off, then back on).  This is helpful for preserving     the contents of RAMdisks when switching programs.  For XL/XE users:     remember to hold [OPTION] down while pressing [G] if you want to     reboot without internal BASIC.                 Pressing [H] will return you to your DOS menu, or to the     command processor if you are using a command processor DOS.                 Disk directories may be done by pressing the drive number     (1-9), then entering the subdirectory pathname to view.  Simply hit     [RETURN] here to view the main directory.  Disk directories may be     also done at the "Enter Source Filemask" prompt, and the Compact with     Query prompts.                                          HOW TO ARC A FILE                 Change any parameters you wish in the top box, then type [A]     to Arc file(s).  Super Arc will now ask you for the destination     filename.  ".ARC" will be added to the filename specified, so you do     not need to specify the extender.  Type the drive identifier and     filename. (Examples: D2:TESTER, D6:FILES>SAMPLE)  Drive 1 (D:) will     be assumed of no "Dx:" is specified.  The program will now open that     destination file.                 Now you will be prompted for the "Source Filemask".  Super Arc     is now asking you which file(s) you want to put into this single     destination file.  If you wanted to arc all files on drive 1, you     would enter "D1:*.*" [RETURN]. To arc only the file "TEST.BAS" on     drive 2, you would enter "D2:TEST.BAS" [RETURN].  This is basically     the same as entering the source when using the copy file feature of     your DOS.  Subdirectories are supported!  To arc all files ending     with .COM on drive 3 subdirectory MOD, use "D3:MOD>*.COM" [RETURN].                 If you set the Compact with Query option to YES, the program     will display each filename it finds, and ask you if you want to arc     it or not.                 The compacting process will now begin.  If the Crunch Only     option is set to YES, the number of bytes saved will be displayed     after the file was compacted.  Otherwise, the resulting size of each     compacting process would occupy will be displayed, along with which     of the three types Super Arc chose.  If the Screen Off option is set     to YES (as it is by default), you will just see the message     "Compacting xxx".  Your screen will be restored after it is done.                 Note for SpartaDOS users:  Super Arc will save the time and     date of each file automatically.  If the source is not in Sparta     format, or if using any other DOS, the date of 09/01/88 and time of     12:00 PM will be saved.                 After the file(s) have been compacted, you will be prompted     for the source filemask again.  If you have any more files to add,     enter them now.  Otherwise, press [RETURN], and your archive will be     complete!  If you ever get a disk error while arcing, the destination     file should be deleted.  It will not have meaningful data.                 If you have an arced file, but want to add some more files to     it, you may use the [B] function from the menu, Add to an Archive.     This functions identically to arcing a file from scratch, except the     data will be added to the destination file you specify.  Be sure your     destination disk has as many sectors free as the length of the Arc     file to which you are adding, because Super Arc must copy the     contents of that file into another temporary file to properly append.     The temporary file is then deleted.  If there are any problems adding     to an arced file (such as if the file you are adding to is not in Arc     format), the message "Cannot add to file" will be displayed.                                    USING SUPER ARC WITH CP DOSES                 You may invoke Super Arc to perform certain functions without     having to use the menu when using Command Processor DOSes such as DOS     XL and SpartaDOS.  Super Arc will return to the CP after it is done,     or upon an error.  The following is the proper syntax:          [Dn:]ARC [Dn:][path>]filename[.ext] Dn:[path>]source [/ACPQSX]     [password]                 The first parameter is the destination filename.  Remember     .ARC will be added to it if you do not specify an extender.  The     second parameter is the source filemask, and the third optional field     is the options desired:     A = Add to the existing source archive     C = Use Crunch only (with SpartaDOS, this isn't really what it means:     re-read the section on Crunch Only for explanation)     P = Use the fourth parameter as an encryption password     Q = Compact with query     S = Have screen remain fully on     X = Enable Disk Swaps                 The default (no third parameter field) is: Screen Off-YES,     Disk Swaps-NO, Compact with Query-NO, Crunch Only-NO, Password-NO.     The fourth parameter is only used if the password [/P] is specified.     Some examples:          [Dn:]ARC D2:TEST D3:*.BAS /QSC                 Will ask you if you want to arc each file on drive 3 ending     with .BAS, leaving the screen on, and enabling the Crunch Only     option.  It will write the result to D2:TEST.ARC.          [Dn:]ARC TEST MYFILE.OBJ /P DATA                 Will compact file MYFILE.OBJ on the current drive, and write     the destination to the file TEST.ARC on the current drive.  It will     use the word "DATA" as a password.          [Dn:]ARC D1:TEST2 D3:*.* /AC                 Will arc all files on drive 3, and add them to the already     existing file TEST2.ARC on drive 1.  It will enable the Crunch Only     option.                                         USING SUPER UN-ARC                 Super Un-Arc operates much like Super Arc, except it is doing     the opposite - Taking a single source, and writing out one or more     destination files.  The following is a list of the parameters in the     top box of Super Un-Arc.  To save space, refer back to the parameter     section of Super Arc for some of these.                 Screen Off:  (same as in Super Arc).                 Disk Swaps:  (same as in Super Arc).                 Over-Write:  This is a safety feature.  If a file already     exists in the directory you have specified with the same name as the     file being uncompacted, Super Arc will ask you if you want to     overwrite your existing file.  Typing [Y] will overwrite it; pressing     [N] or [RETURN] will skip the file and proceed to the next entry.     Pressing [ESC] will abort the unarcing process.  All the above will     take place if the Over-Write option is set to NO.  Setting it to YES     will not prompt you, and will overwrite any files having the same     name.                 Extract with Query:  If this option is set to YES, the program     will display each entry in the arced file, and ask you if you wish to     uncompact it.  This is handy for viewing just the text files in an     archive.  Setting this option to NO will extract all files.                 Time/Date Stamp:  This option is valid only under SpartaDOS.     Setting this option to YES will cause the destination files to be     written out with the original time and date of the file when it was     first Archived.  Some arc programs do not save the time and date, so     if you get a bogus value, you know why.  If this option is set to NO     (as it is by default), the current time and date will be used.                 Password Encrypt:  This option is to be used when the source     file has been encrypted with a password.  If this option is set to     YES, you will be asked for the password after entering the     destination pathname.  Pressing [RETURN] will disable the password     (incase you inadvertently turned it on).  The password can be 1-20     characters long, and is not inverse or case sensitive.  If you use     the wrong password, you may get a "File is Corrupted" message, but     the destination file will be corrupted.                 As with Super Arc, the [D]elete, [F]ormat, [G] Reboot, [H]     Return to DOS, and [1-9] directories function just as in Super Arc.     See the section entitled 'Using Super Un-Arc with CP DOSes' for     information concerning passing parameters to Super Un-Arc.                 You may view the contents of an arced file by typing [V].     Enter the source filename.  ".A??" is added to the end of the source     filename you enter, so if the extender is .ARC or .ALF (for Arc and     AlfCrunch, respectively), the file will be read.          ** PLEASE NOTE IF THE SOURCE FILE HAS NO EXTENDER, ADD A [.] PERIOD     AFTER THE SOURCE FILENAME! **          This means if you have a file on drive 3 named TEST (no extender),     you should enter "D3:TEST.".  If the file was named TEST.ARC, then     you would only have to enter "D3:TEST".  When viewing a file, each     filename, compaction method, and expanded sector size (in     single-density sectors) will be shown.  The total number of single or     enhanced density free sectors needed to uncompact all the files will     be displayed at the end.  When using double-density, divide the     counts by 2 (approximately).                                         HOW TO UNARC A FILE                 To un-arc or un-alfcrunch a file, first change any parameters     you wish in the top box; then type [A].  Enter the source filename     (and extender if it is not .ARC or .ALF - see the paragraph on     [V]iewing files for information on the source filename).  If the file     is not found, an "Error 170" will result.  You may then use the     directory functions to locate the correct name, and try again.                 You will now be prompted for "The destination pathname or     drive # (& mask)".  Entering data at this prompt will do two things:     it will tell Super Un-Arc where to put the destination file(s), and     it will also tell which files you wish to recover.  If you wanted to     extract all files and place them on drive 2, you would simply press     [2] and [RETURN].  If you wanted to place them in a subdirectory     called "SUBDIR" on drive 3, you would use "D3:SUBDIR>".  You may also     use "E:" to make the output go to the screen (for viewing text files:     use Control 1 to start and stop), or P: to route the output to your     printer.  Using "N:" will extract each file, but throw away the data     (N for Null device).  The use for this feature is to test the     integrity of the source file (to see if there might be some bad bytes     in it).                 Also with this prompt, you may select which files to extract     from the archive file.  For example, if you viewed a sample arc file     and found two .DOC files, you could print them out by unarcing to     "P:*.DOC".  The same thing applies to disk files; to extract all     files ending with .BAS in an archive to drive 1, use "D1:*.BAS".     (Just "D1:" by itself will extract all files.)  Wild cards are not     necessary; if you wanted to extract a single file, you could just     type in that filename after the destination drive identifier.  So     there are two ways to extract certain files: enable the Extract with     Query option, and/or specify the filespec when entering the     destination filemask.                 The uncompressing process will now begin.  Each filename,     compression type, uncompacted length in single-density sectors, and     the number of bytes saved by the compaction will be displayed.  If     you specified a subdirectory for the destination and it is not found,     Super Un-Arc will ask you if you wish to create the directory.     Subdirectories are supported for MYDOS and SpartaDOS.  If a file     exists on your destination with the same name as the one you are     about to uncompact, the program will ask you if you wish to overwrite     the file ONLY IF the Over-write option is set to NO.                 If you have turned on the "Extract with Query" option, the     program will prompt you if you wish to extract the file displayed.     Pressing [Y] will extract it, [N] will skip and go to the next entry,     [P] will allow you to change the destination drive number/path/mask,     [1-9] will allow you disk directories, and [ESC] will terminate the     un-arcing process.                 If Super Un-Arc has a problem opening up the destination file,     you will be given an error recovery menu.  This will allow you to     change the destination drive number/path/mask, and do directories.     If you gave the wrong drive number, or your destination was     write-protected, you can fix it here, then press [RETURN] to     continue.  If you wish to bail out, press [ESC].                 If you have the "Screen Off" set to yes (as it is by default),     you will only see each filename as it uncompacts.  If you have the     "Disk Swaps" set to yes, the screen will remain on, so that you can     see when to insert the proper disk.  If the screen is "off" and you     wish to turn it on, Press [SPACE].  When Super Un-Arc extracts the     next file, the screen will be restored.                 The uncompressing process will continue until completion or a     major error.  If you get the message "File fails CRC check", that     file is corrupted and should probably be discarded.  The version 1.2     of Arc program written by Ralph Walden had a bug that caused this to     occur quite often, sometimes because it DID put bad bytes in the     file, other times not.  If you see a file that was "Squeezed" with a     CRC error, it was probably caused by this 1.2 Arc program - Use the     file at your own risk.  If you get CRC errors on any other type of     compacted file, the files ARE bad!  If the CRC error is followed by     the messages "Not an ARC or ALFCRUNCH file" or "File is corrupted",     the source file is bad.  You may occasionally get the message "Not an     ARC or ALFCRUNCH file" at the end of uncompacting an AlfCrunch file.     This is due to extra bytes at the end of the file caused by improper     X-modem routines; but all the file(s) will be intact.                 Super Un-Arc 2.3 now supports un-squashing, a method do     compaction recently introduced by IBM, ST, and commodore computers.     This new method of compaction requires 16K of additional memory;     memory that is really not available on the standard 8-bit Atari.     However, if you have a 130XE, upgraded 800XL, or an Axlon-compatible     upgraded 800, the last bank of extra memory in these machines will be     used.  Un-squashing is totally automatic - it is used just like the     other methods.  If you do not have any extra memory, and you try to     unarc a file that was squashed, the program will give you the message     "You need >=128K to unsquash", and will end.                 When viewing or uncompressing a file, Super Un-Arc verifies     that the file was indeed created by Arc or AlfCrunch.  If it is not,     it checks to see if the source file was compacted with Diskcomm, or     is a binary file.  It will report what it finds, or "Not an Arc or     AlfCrunch file" is it cannot determine.  If there are any garbage     bytes at the beginning of the file (caused by older terminal     programs), the program will search ahead to find the true start.                                  USING SUPER UN-ARC WITH CP DOSES                 As in Super Arc, the program supports parameter passing with     command processor DOSes such as DOS XL and SpartaDOS.  If there are     no parameters specified, or if they are in an improper syntax, the     program will ignore them, and display the menu.  This is the proper     syntax for Super Unarc:          [Dn:]UNARC [Dn:][path>]filename[.ext] Dn:[path>][mask] [/OPQSTX]     [password]                 The first parameter is the source file (remember ".A??" will     be added to the name, so specify the extender if it does not begin     with .A), the second is the destination drive number, or path (and     mask), and the third optional parameter is the options desired:     O = Over-Write set to YES, will overwrite any file with the same name     as the destination     P = Use a encryption password (the fourth parameter, which is only     used with this option)     Q = Extract files with Query set to YES     S = Have screen remain full during uncompaction     T = Use time/date stamp from source file when writing destination     files     X = Disk Swaps set to YES, for single drive users                 You may specify none, any, or all (in any order).  The default     without any options is: Screen Off:YES, Disk Swaps:NO, Over-Write:NO,     Extract with Query:NO, Time/Date stamp:NO, Password encrypt:NO.  The     fourth parameter is only used if the password [/P] is enabled.  Some     examples:          [Dn:]UNARC D2:TEST 3 /QS                 Will uncompact the file D2:TEST.A?? to drive 3, extract with     query, and have the screen remain on.          [Dn:]UNARC TEST.JNK P:*.DOC /P DATA                 Will uncompact all .DOC files to the printer from the file     TEST.JNK on the current drive.  It will use the word "DATA" as the     password to unencrypt the archive.          [Dn:]UNARC D7:MOD>MYFILE N:                 Will verify the integrity of the file MYFILE.A?? in the     subdirectory MOD of drive 7.                                          CLOSING COMMENTS                 I had originally desired to put both Arc and Unarc programs     into one, but due to memory constrictions, this was not possible.     Both programs require tables over 16K in length, so it leaves little     for the program itself.  In fact, if you use Super Arc or Un-Arc with     a cartridge installed, you will have VERY small I/O buffers.                 I would like to take the time to thank all the people who have     helped by debugging, giving hints, etc, but this file would be 10K     longer! :-)  However, a special thanks goes out to all GEnie users,     who helped test these two programs, and to Frank Walters, for his     intensive de-bugging efforts!  Also a special thanks to Glenn Garman,     who makes sure everyone can understand my documentation!                 A good deal of time has been spent on these programs - much     longer than I intended.  The public domain, however, needed a good     Arc and Unarc program.  So I have released this program as Shareware.     What this means is that you may use it as you like, and give it to     your friends, clubs, etc, without cost.  However, I would ask that     you consider the time and effort involved in creating a program such     as this.  Making it compatible with all DOSes was no small feat!  If     you enjoy the program, consider sending a token of your appreciation.     This will provide incentives for me to keep updating and writing     other quality utilities for the Atari 8-bit.  If you have any     suggestions, donations, comments, etc, please send them to:                         Robert Puff                    Suite 222                    2117 Buffalo Rd                    Rochester, N.Y. 14624                 I may also be reached on GEnie (mail address is BOB.PUFF), and     on these local BBS's:          The Moose BBS      (716) 381-5139     The Lakeside Manor (716) 338-2453                                           TECHNICAL NOTES                 Super Arc & UnArc both use the vectors provided at HATABS for     screen and keyboard I/O, so re-direction should present no problems.     Both programs load in at $6F00, then relocate to LOMEM.  If there is     not enough room between LOMEM and HIMEM, the programs will display an     out-of-memory message, end exit.  The remainder of memory from the     end of the program to HIMEM is used by input/output buffers; the     bigger the buffer the faster the program will run.  (Super Arc will     just fit when a cartridge is present.)  Built-in BASIC will be     disabled automatically, unless SpartaDOS is detected.  The programs     detect Sparta by looking for a "S" in location $0700.                 A graphics 0 call is made when the program exits, to maintain     compatibility with programs that play with the display list such as     TDLINE.  Screen memory is saved, so the data on the screen is     preserved.  If you wish to include Super Arc & UnArc in specific     application software (such as a graphical Operating System), please     get in touch with me, as small modifications to the program could be     easily done.                 If you are using MYDOS version 4.0 thru 4.3C, you may wish to     upgrade to version 4.4.  Super Arc & UnArc will work correctly with     the older versions, but certain functions will be much slower. The     new version 4.4 of the DOS at the time of this writing is about to be     released to the public domain, so obtaining the new version should     not be a problem.                 Both Super Arc & UnArc support three delimiters for separating     subdirectory names: The colon [:], the greater-than sign [>], and the     backslash [\].          Bob Puff  11/21/88          P.S. A version 2.1 of UnArc managed to sneek out the same time a     small bug in the program was discovered.  Also, version 2.2 of UnArc     had a bug in uncompacting very large squeezed files.  If you have or     see this version, or any earlier version of this program for that     matter, please delete them.          